.TH lustre_rsync 8 "2009 Apr 08" Lustre "Lustre Filesystem replication utility"
.SH NAME
lustre_rsync \- Utility to replicate a Lustre Filesystem
.SH SYNOPSIS
.br
.B lustre_rsync --source|-s <src> --target|-t <tgt> 
.br
.B\t\t\t --mdt|-m <mdt>  [--user|-u <user id>] 
.br
.B\t\t\t [--xattr|-x <yes|no>] [--verbose|-v]
.br
.B\t\t\t [--statuslog|-l <log>] [--dry-run] [--abort-on-err]
.br

.br
.B lustre_rsync  --statuslog|-l <log>
.br

.br
.B lustre_rsync  --statuslog|-l <log> --source|-s <source>
.br
.br
.B\t\t\t --target|-t <tgt> --mdt|-m <mdt>
.SH DESCRIPTION
.B lustre_rsync
is designed to replicate a Lustre filesystem (source filesystem) to
another target filesystem (any filesystem type) efficiently by 
using Lustre MDT changelogs.  A changelog user must be registered
(see lctl (8) changelog_register) before using this tool.

The source and the target filesystems must be identical before
the changelog user is registered. If the filesystems are discrepant,
a utility like rsync may be used to make them identical.

.SH OPTIONS
.B --source=<src>
.br
The path to the root of the Lustre filesytem which will be replicated. 
Mandatory if a valid statuslog created during an previous replication operation
(--statuslog) is not specified.

.B --target=<tgt>
.br
The path to the root where the filesystem we be replicated. Mandatory
if a valid statuslog created during an previous replication operation
(--statuslog) is not specified. This option can be repeated if
multiple replication targets are desired.

.B --mdt=<mdt>
.br
The metadata device which is to be replicated. A changelog user must be
registered for this device. Mandatory if a valid statuslog created
during an previous replication operation (--statuslog) is not
specified.

.B --user=<user id>
.br
The changelog user id for the above MDT device. See lctl(8) changelog_register.
Mandatory if a valid statuslog created during an previous replication operation
(--statuslog) is not specified.

.B --statuslog=<log>
.br
A status log file to which the status of replication is saved. 
When lustre_rsync is started, the state from a previous replication
will be read from here.

If a statuslog from a previous replication operation is specified, the
otherwise mandatory options like --source, --target and --mdt may be
skipped.

By specifying the options like --source, --target and --mdt in
addition to the --statuslog option, the parameters in the statuslog
can be overridden. The command line options take precedence over the
ones from the statuslog.

.B --xattr <yes|no>
.br
Specify whether extended attributes are replicated or not. The default
is to replicate extended attributes. Disabling xattrs will mean that
Lustre striping information will not be replicated.

.B --verbose
.br
Produce a verbose output.

.B --dry-run
.br
Shows what the program would do without actually replicating data.

.B --abort-on-err
.br
Stop processing upon first error.  Default is to continue processing.

.SH EXAMPLES

.TP
Register a changelog consumer for MDT lustre-MDT0000
$ ssh $MDS lctl changelog_register \\
.br
	     --device lustre-MDT0000 -n
.br
cl1

.TP
Replicate the lustre filesystem /mnt/lustre to /mnt/target.
$ lustre_rsync --source=/mnt/lustre --target=/mnt/target \\ 
.br
             --mdt=lustre-MDT0000 --user=cl1 \\
.br
             --statuslog replicate.log  --verbose
.br
Lustre filesystem: lustre
.br
MDT device: lustre-MDT0000
.br
Source: /mnt/lustre
.br
Target: /mnt/target
.br
Statuslog: replicate.log
.br
Changelog registration: cl1
.br
Starting changelog record: 0
.br
Errors: 0
.br
lustre_rsync took 1 seconds
.br
Changelog records consumed: 22
.br


.TP
After the filesystem undergoes some changes, replicate the \
changes. Only the statuslog needs to be specified as it has all the \
parameters passed earlier.
.br
$ lustre_rsync --statuslog replicate.log --verbose
.br
Replicating Lustre filesystem: lustre
.br
MDT device: lustre-MDT0000
.br
Source: /mnt/lustre
.br
Target: /mnt/target
.br
Statuslog: replicate.log
.br
Changelog registration: cl1
.br
Starting changelog record: 22
.br
Errors: 0
.br
lustre_rsync took 2 seconds
.br
Changelog records consumed: 42
.br

.TP
To replicate the lustre filesystem /mnt/lustre to /mnt/target1 and /mnt/target2.
$ lustre_rsync --source=/mnt/lustre \\ 
.br
             --target=/mnt/target1 --target=/mnt/target2 \\ 
.br
             --mdt=lustre-MDT0000 --user=cl1
.br
             --statuslog replicate.log
.br


.SH AUTHOR
The lustre_rsync command is part of the Lustre filesystem.

.SH SEE ALSO
.BR lustre (7),
.BR lctl (8),
.BR lfs (1)
